---
layout: docs
page_title: Install the Vault EKM provider
description: Installation steps for the Vault EKM provider for Microsoft SQL Server.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# Install the Vault EKM provider

This guide assumes you are installing the Vault EKM Provider for the first time.
For upgrade instructions, see [upgrading](/vault/docs/platform/mssql/upgrading).

## Prerequisites

* Vault Enterprise server 1.9+ with a license for the Advanced Data Protection Key Management module
* Microsoft Windows Server operating system
* Microsoft SQL Server 2012 or newer for Windows (Windows SQL Server Express and SQL Server for Linux [does not support EKM][linux-ekm])
* An authenticated Vault client

To check your Vault version and license, you can run:

```bash
vault status
vault license get -format=json
```

The list of features should include "Key Management Transparent Data Encryption".

[linux-ekm]: https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-editions-and-components-2019?view=sql-server-ver15#Unsupported

## Installing the Vault EKM provider

## Configuring Vault

The EKM provider requires AppRole auth and the Transit secret engine to be setup
on the Vault server. The steps below can be used to configure Vault ready for the
EKM provider to use it.

-> **Note:** rsa-2048 is currently the only supported key type.

1. Set up AppRole auth:

    ```bash
    vault auth enable approle
    vault write auth/approle/role/ekm-encryption-key-role \
        token_ttl=20m \
        max_token_ttl=30m \
        token_policies=tde-policy
    ```

-> **Note:** After authenticating to Vault with the AppRole, the EKM provider
will re-use the token it receives until it expires, at which point it will
authenticate using the AppRole credentials again; it will not attempt to renew
its token. The example AppRole configuraiton here will work for this, but keep
that in mind if you choose to use a different AppRole configuration.

1. Retrieve the AppRole ID and secret ID for use later when configuring SQL Server:

    ```bash
    vault read auth/approle/role/ekm-encryption-key-role/role-id
    vault write -f auth/approle/role/ekm-encryption-key-role/secret-id
    ```

1. Enable the transit secret engine and create a key:

    ```bash
    vault secrets enable transit
    vault write -f transit/keys/ekm-encryption-key type="rsa-2048"
    ```

1. Create a policy for the Vault EKM provider to use. The following policy has
    the minimum required permissions:

    ```bash
    vault policy write tde-policy -<<EOF
    path "transit/keys/ekm-encryption-key" {
        capabilities = ["create", "read", "update", "delete"]
    }

    path "transit/keys" {
        capabilities = ["list"]
    }

    path "transit/encrypt/ekm-encryption-key" {
        capabilities = ["update"]
    }

    path "transit/decrypt/ekm-encryption-key" {
        capabilities = ["update"]
    }

    path "sys/license/status" {
        capabilities = ["read"]
    }
    EOF
    ```

## Configuring SQL server

The remaining steps are all run on the database server.

### Install the EKM provider on the server

1. Download and run the latest Vault EKM provider installer from
  [releases.hashicorp.com](https://releases.hashicorp.com/vault-mssql-ekm-provider/)
1. Run the installer to create an initial configuration. If your server URL is
   too long for the input field, you can set it manually in the next step.
1. If you need to configure non-default namespaces or mount paths or your server
   URL exceeds the character limit in the installer, set the relevant
   [EKM configuration parameters](/vault/docs/platform/mssql/configuration)
   manually in your configuration file:

    <Tabs>
    <Tab heading="Self-managed Vault">

    ```hcl
    {
      "namespace": "<custom_namespace>",
      "appRoleMountPath": "<custom_approle_path>",
      "transitMountPath": "<custom_approle_path>",
      "enableTrace": "true",
      "vaultApiBaseUrl": "<server_url>"
    }
    ```

    </Tab>
    <Tab heading="HCP Vault Dedicated">

    ```hcl
    {
      "namespace": "admin/<custom_namespace>",
      "appRoleMountPath": "<custom_approle_path>",
      "transitMountPath": "<custom_approle_path>",
      "enableTrace": "true",
      "vaultApiBaseUrl": "<server_url>"
    }
    ```

    </Tab>
    </Tabs>

### Configure the EKM provider using SQL

Open Microsoft SQL Server Management Studio, and run the queries below to complete
installation.

1. Enable the EKM feature and create a cryptographic provider using the folder
   you just installed the EKM provider into.

    ```sql
    -- Enable advanced options
    USE master;
    GO

    EXEC sp_configure 'show advanced options', 1;
    GO

    RECONFIGURE;
    GO

    -- Enable EKM provider
    EXEC sp_configure 'EKM provider enabled', 1;
    GO

    RECONFIGURE;
    GO

    CREATE CRYPTOGRAPHIC PROVIDER TransitVaultProvider
    FROM FILE = 'C:\Program Files\HashiCorp\Transit Vault EKM Provider\TransitVaultEKM.dll'
    GO
    ```

1. Next, create credentials for an admin to use EKM with your AppRole role and
    secret ID from above:

    ```sql
    -- Replace <approle-role-id> and <approle-secret-id> with the values from
    -- the earlier vault commands:
    -- vault read auth/approle/role/ekm-encryption-key/role-id
    -- vault write -f auth/approle/role/ekm-encryption-key/secret-id
    CREATE CREDENTIAL TransitVaultCredentials
        WITH IDENTITY = '<approle-role-id>',
        SECRET = '<approle-secret-id>'
    FOR CRYPTOGRAPHIC PROVIDER TransitVaultProvider;
    GO

    -- Replace <domain>\<login> with the SQL Server administrator's login
    ALTER LOGIN "<domain>\<login>" ADD CREDENTIAL TransitVaultCredentials;
    ```

1. You can now create an asymmetric key using the transit key set up earlier:

    ```sql
    CREATE ASYMMETRIC KEY TransitVaultAsymmetric
    FROM PROVIDER TransitVaultProvider
    WITH
    CREATION_DISPOSITION = OPEN_EXISTING,
    PROVIDER_KEY_NAME = 'ekm-encryption-key';
    ```

    -> **Note:** This is the first step at which the EKM provider will communicate with Vault. If
    Vault is misconfigured, this step is likely to fail. See
    [troubleshooting](/vault/docs/platform/mssql/troubleshooting) for tips on specific error codes.

1. Create another login from the new asymmetric key:

    ```sql
     -- Replace <approle-role-id> and <approle-secret-id> with the values from
    -- the earlier vault commands again
    CREATE CREDENTIAL TransitVaultTDECredentials
        WITH IDENTITY = '<approle-role-id>',
        SECRET = '<approle-secret-id>'
    FOR CRYPTOGRAPHIC PROVIDER TransitVaultProvider;
    GO

    CREATE LOGIN TransitVaultTDELogin
    FROM ASYMMETRIC KEY TransitVaultAsymmetric;
    GO

    ALTER LOGIN TransitVaultTDELogin
    ADD CREDENTIAL TransitVaultTDECredentials;
    GO
    ```

1. Finally, you can enable TDE and protect the database encryption key with
   the asymmetric key managed by Vault's Transit secret engine:

    ```sql
    CREATE DATABASE TestTDE
    GO

    USE TestTDE;
    GO

    CREATE DATABASE ENCRYPTION KEY
    WITH ALGORITHM = AES_256
    ENCRYPTION BY SERVER ASYMMETRIC KEY TransitVaultAsymmetric;
    GO

    ALTER DATABASE TestTDE
    SET ENCRYPTION ON;
    GO
    ```

1. Check the status of database encryption using the following queries:
    ```sql
    SELECT * FROM sys.dm_database_encryption_keys;

    SELECT (SELECT name FROM sys.databases WHERE database_id = k.database_id) as name,
        encryption_state, key_algorithm, key_length,
        encryptor_type, encryption_state_desc, encryption_scan_state_desc FROM sys.dm_database_encryption_keys k;

    ```

## Key rotation

See [key rotation](/vault/docs/platform/mssql/rotation) for guidance on rotating
the encryption keys.
